home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / MorphOS / Epic4_mos / share / epic / help / 6_functions / finditem < prev    next >
Encoding:
Text File  |  2002-10-28  |  1.8 KB  |  47 lines
  1. Synopsis:
  2.    $finditem(<array> <string>)
  3.    $ifinditem(<array> <string>)
  4.    $ifindfirst(<array> <string>)
  5.  
  6. Technical:
  7.    These functions do a binary search on the items stored in the given
  8.    array, looking for an exact match of the input string.  It will only
  9.    return the results of an exact match.  Unlike other string handlers in
  10.    the client, these are case-sensitive.  They only operate on arrays
  11.    created with the $setitem() function.
  12.  
  13.    These functions differ only in which exact match they will return.  The
  14.    $finditem() function returns the item number of the first match found;
  15.    it does not check the array sequentially, so other exact matches with
  16.    lower item numbers may not be returned.  The $ifinditem() function is
  17.    same, except it returns the index number of the first match found (also
  18.    regardless of the actual indexing order).  The $ifindfirst function is
  19.    similar to $ifinditem(), except it returns the first exact match after
  20.    the array has been sorted.
  21.  
  22. Practical:
  23.    These functions are useful when you want to see if a particular string is
  24.    present in an array.  Being sensitive to case, they are more precise than
  25.    the general pattern-matching functions.
  26.  
  27. Returns:
  28.      -2   item not found in array
  29.      -1   array does not exist
  30.    > -1   item/index number that matches input
  31.  
  32. Examples:
  33.    /* contrived sample array */
  34.    $setitem(booya 0 blah)
  35.    $setitem(booya 1 foobar)
  36.    $setitem(booya 2 blah)
  37.  
  38.    $finditem(booya blah)                   returns 0
  39.    $ifinditem(booya blah)                  returns 1
  40.    $ifindfirst(booya blah)                 returns 0
  41.    $finditem(booya Blah)                   returns -1
  42.    $finditem(foobar blah)                  returns -2
  43.  
  44. See Also:
  45.    Arrays(7); getitem(6); setitem(6)
  46.  
  47.